Home



Introducing {gs}:
A grammar of recurring calendar events


James Laird-Smith

The Financial Times (FT)

Simple examples

Every 35 days

 [1] "2020-01-28"
 [2] "2020-03-03"
 [3] "2020-04-07"
 [4] "2020-05-12"
 [5] "2020-06-16"
 [6] "2020-07-21"
 [7] "2020-08-25"
 [8] "2020-09-29"
 [9] "2020-11-03"
[10] "2020-12-08"

To schedule days in increments from a certain date, we use the on_every_nth() function.

In this case we specify:

  1. The number of increments between events is 35
  2. The type of increment is “days”
  3. The start date is today.

Friday the 13th

[1] "2020-03-13"
[2] "2020-11-13"
[3] "2021-08-13"
[4] "2022-05-13"

Friday the 13th can be thought of as the intersection of:

  1. The schedule of all Fridays, found using the on_wday() function.
  2. The schedule of all 13th days of the month, using the on_mday() function.

The intersection of these two schedules is found by passing them as arguments to the also_occur() function.

The Monday of the 20th week of the year

[1] "2020-05-11"
[2] "2021-05-17"
[3] "2022-05-16"
[4] "2023-05-15"
[5] "2024-05-13"
[6] "2025-05-12"

This schedule can be created as the intersection of two schedules:

  1. The schedule of Mondays, created using the on_wday() function.
  2. The schedule of events occurring in ISO week 20, created using the in_isoweek() function.

The intersection of these schedules is found using the only_occur() function.

Advanced examples

Every 12th Monday, Wednesday or Friday of the year

[1] "2020-01-27"
[2] "2021-01-27"
[3] "2022-01-28"
[4] "2023-01-27"
[5] "2024-01-26"
[6] "2025-01-27"

This is a compound schedule with the following parts:

  1. Days occurring on Monday, Wednesday or Friday.
  2. The 12th occurrence of an event within a period.

We can create the first schedule using the on_wday() function.

We can then use that schedule object as an argument to the on_nth() function where we also specify that we want the 12th occurrence and that it should be within each given year.

Every 5th last Friday or Saturday of the month

 [1] "2020-01-17"
 [2] "2020-02-15"
 [3] "2020-03-14"
 [4] "2020-04-11"
 [5] "2020-05-16"
 [6] "2020-06-13"
 [7] "2020-07-17"
 [8] "2020-08-15"
 [9] "2020-09-12"
[10] "2020-10-17"
[11] "2020-11-14"
[12] "2020-12-12"

Just like the previous example, this can be accomplished as a compound schedule:

  1. The first thing is to make the schedule of Fridays and Saturdays using the on_wday() function.
  2. This schedule is then used as an argument to the on_nth() function where we also specify -5 as the first argument.

The negative integer tells the on_nth() function to look for the last occurrence of the event within the particular period rather than the first.

The first Saturday following the first Sunday of the month

 [1] "2020-01-11"
 [2] "2020-02-08"
 [3] "2020-03-07"
 [4] "2020-04-11"
 [5] "2020-05-09"
 [6] "2020-06-13"
 [7] "2020-07-11"
 [8] "2020-08-08"
 [9] "2020-09-12"
[10] "2020-10-10"
[11] "2020-11-07"
[12] "2020-12-12"

There are two components to the schedule:

  1. The first Sunday of the month, found using the on_wday() and on_first() functions.
  2. The Saturday following the above schedule, found by rolling it forward using the roll_forward() function.

Holidays

U.S. Independence Day

[1] "2020-07-04"
[2] "2021-07-04"
[3] "2022-07-04"
[4] "2023-07-04"
[5] "2024-07-04"
[6] "2025-07-04"

In the United States Independence Day is celebrated on July 4th, regardless of the year.

This can be created as the intersection of two schedules:

  1. The schedule of days occurring in July, found using the in_month() function.
  2. The schedule of all days occurring on the 4th of the month, found using the on_mday().

The intersection of these schedules is found using the only_occur() function.

Martin Luther King Jr. Day

[1] "2020-01-20"
[2] "2021-01-18"
[3] "2022-01-17"
[4] "2023-01-16"
[5] "2024-01-15"
[6] "2025-01-20"

Martin Luther King Jr. Day is a national holiday United States occurring every year on the third Monday in January.

There are three parts to this schedule:

  1. Events occurring on Mondays, created using on_wday().
  2. Events occurring in January, created using in_month()
  3. The schedule of the nth event occurring in the period, in this case on_third().

The schedule of Mondays is passed into the on_third() function as an argument along with the argument specifying it should be within a given month.

You can then get the desired schedule by finding the intersection of the above schedule with the schedule of January days using only_occur().

Combine holidays

[1] "2020-01-20"
[2] "2020-07-04"
[3] "2021-01-18"
[4] "2021-07-04"
[5] "2022-01-17"
[6] "2022-07-04"

If you want to create a schedule of multiple holidays, you can compose it using individual schedule objects of those holidays.

In this example, we take the schedule objects we have already created for US Independence Day and Martin Luther King Jr. Day and combine them using the also_occur() function.

This can be done any number of times to create a schedule that is arbitrarily complex.